---
title: Endpoints
summary: Endpoint catalog for the DBConnectionAPI REST API, with per-controller detail pages.
status: draft
owner: Architecture
last_reviewed: 2026-10-09
---

# Endpoints

DBConnectionAPI exposes two controllers with six endpoints in total: three `GET` retrieval endpoints on `ConnectionsController` that return a composed connection string, and three `POST` inspection endpoints on `AdminController` that return the raw credential parts. All routes are attribute-routed and carry a literal `v1` prefix.

This page is the endpoint catalog and hub. Each controller's endpoints are documented in detail on its own page under `endpoints/`.

## Route composition

| Aspect | Finding |
| --- | --- |
| Routing mode | Attribute routes (`[ApiController]` + `[Route]`) |
| Controller route template | `v1/Connections` on `ConnectionsController`; `v1/Admin` followed by the action name on `AdminController` (the class-level `[Route]` templates use a controller-name token) |
| Versioning | Literal `v1` prefix — not API versioning; see [Hosting pipeline](hosting-pipeline.md#api-versioning) |
| Base path | `/` (the IIS application path is deployment-defined and not determined from source) |

A resolved route is the controller `[Route]` template composed with the action's `[HttpGet("<template>")]`, with the controller-name token replaced by the controller name minus its `Controller` suffix and the action-name token by the action name. `ConnectionsController` actions each declare an `[HttpGet]` template. `AdminController` actions declare a bare `[HttpPost]`, so the action name supplies the last segment. Query-string parameters are listed on each endpoint page, not in the route.

## Controller catalog

| Controller | Route template | API version | Base | Endpoints | Documentation |
| --- | --- | --- | --- | --- | --- |
| `AdminController` | `v1/Admin` plus the action name | — | `ControllerBase` | 3 | [Details](endpoints/admin.md) |
| `ConnectionsController` | `v1/Connections` | — | `ControllerBase` | 3 | [Details](endpoints/connections.md) |

## Endpoint catalog

Neither controller declares `[ProducesResponseType]`, so every non-200 status listed below is undeclared in source. All endpoints are protected by the same resource requirement (see [Authentication and authorization](authentication-authorization.md#authorization-enforcement)). The endpoints return credential material (CRITICAL, see [Authentication and authorization](authentication-authorization.md#security-findings)).

| Endpoint | Controller | Action | Auth | Success | Errors | Rules |
| --- | --- | --- | --- | --- | --- | --- |
| [`POST /v1/Admin/GetOracleConnectionInfo`](endpoints/admin.md#post-v1-admin-getoracleconnectioninfo) | `AdminController` | `GetOracleConnectionInfo` | [`DBConnAPIRetrieveResource`](authentication-authorization.md#authorization-enforcement) | `200 OK` | `401`/`403` **, `500` ** | [BR-DBC-023](business-rules.md#br-dbc-023-admin-inspection-discloses-raw-credentials), [BR-DBC-024](business-rules.md#br-dbc-024-admin-split-failure-reported-with-status-200), [BR-DBC-025](business-rules.md#br-dbc-025-resource-authorization-on-every-endpoint) |
| [`POST /v1/Admin/GetPostgresConnectionInfo`](endpoints/admin.md#post-v1-admin-getpostgresconnectioninfo) | `AdminController` | `GetPostgresConnectionInfo` | [`DBConnAPIRetrieveResource`](authentication-authorization.md#authorization-enforcement) | `200 OK` | `401`/`403` **, `500` ** | [BR-DBC-006](business-rules.md#br-dbc-006-postgresql-credentials-ignore-the-server), [BR-DBC-023](business-rules.md#br-dbc-023-admin-inspection-discloses-raw-credentials), [BR-DBC-024](business-rules.md#br-dbc-024-admin-split-failure-reported-with-status-200), [BR-DBC-025](business-rules.md#br-dbc-025-resource-authorization-on-every-endpoint) |
| [`POST /v1/Admin/GetSqlConnectionInfo`](endpoints/admin.md#post-v1-admin-getsqlconnectioninfo) | `AdminController` | `GetSqlConnectionInfo` | [`DBConnAPIRetrieveResource`](authentication-authorization.md#authorization-enforcement) | `200 OK` | `401`/`403` **, `500` ** | [BR-DBC-023](business-rules.md#br-dbc-023-admin-inspection-discloses-raw-credentials), [BR-DBC-024](business-rules.md#br-dbc-024-admin-split-failure-reported-with-status-200), [BR-DBC-025](business-rules.md#br-dbc-025-resource-authorization-on-every-endpoint) |
| [`GET /v1/Connections/ORA/{instance}/{username}`](endpoints/connections.md#get-v1-connections-ora-instance-username) | `ConnectionsController` | `GetOraConnectionString` | [`DBConnAPIRetrieveResource`](authentication-authorization.md#authorization-enforcement) | `200 OK` | `400`, `404`, `500`, `401`/`403` ** | [BR-DBC-001](business-rules.md#br-dbc-001-serve-from-the-cache-when-the-key-is-present), [BR-DBC-009](business-rules.md#br-dbc-009-missing-secure-setting-returns-404), [BR-DBC-015](business-rules.md#br-dbc-015-tns-alias-errors-map-to-400), [BR-DBC-016](business-rules.md#br-dbc-016-other-final-failures-map-to-500), [BR-DBC-025](business-rules.md#br-dbc-025-resource-authorization-on-every-endpoint) |
| [`GET /v1/Connections/PostgreSQL/{instance}/{username}`](endpoints/connections.md#get-v1-connections-postgresql-instance-username) | `ConnectionsController` | `GetPostgreSqlConnectionString` | [`DBConnAPIRetrieveResource`](authentication-authorization.md#authorization-enforcement) | `200 OK` | `404`, `500` **, `401`/`403` ** | [BR-DBC-006](business-rules.md#br-dbc-006-postgresql-credentials-ignore-the-server), [BR-DBC-020](business-rules.md#br-dbc-020-postgresql-strings-are-never-probed), [BR-DBC-021](business-rules.md#br-dbc-021-blank-postgresql-server-becomes-a-placeholder), [BR-DBC-025](business-rules.md#br-dbc-025-resource-authorization-on-every-endpoint) |
| [`GET /v1/Connections/SQL/{server}/{instance}/{username}`](endpoints/connections.md#get-v1-connections-sql-server-instance-username) | `ConnectionsController` | `GetSqlConnectionString` | [`DBConnAPIRetrieveResource`](authentication-authorization.md#authorization-enforcement) | `200 OK` | `400 *`, `404`, `500`, `401`/`403` ** | [BR-DBC-001](business-rules.md#br-dbc-001-serve-from-the-cache-when-the-key-is-present), [BR-DBC-009](business-rules.md#br-dbc-009-missing-secure-setting-returns-404), [BR-DBC-016](business-rules.md#br-dbc-016-other-final-failures-map-to-500), [BR-DBC-018](business-rules.md#br-dbc-018-probe-validity-definition), [BR-DBC-025](business-rules.md#br-dbc-025-resource-authorization-on-every-endpoint) |


The `400 *` on the SQL Server endpoint arises only if a TNS-alias-style lookup error is surfaced by the SQL Server path. This is inferred, not confirmed; the confirmed 400 mapping is Oracle-only ([BR-DBC-015](business-rules.md#br-dbc-015-tns-alias-errors-map-to-400)).

### Error mechanisms

Two mechanisms produce error responses across the surface. Their body shapes are not visible in source for the first one.

| Mechanism | Endpoints covered | Behavior |
| --- | --- | --- |
| `ConnectionManagerException : HttpStatusCodeException` thrown by `ConnectionManager`, handled by package middleware `DynamicErrorHandler` contributed by `SAIF.NetCore.ServiceExtensions` † | The three `ConnectionsController` endpoints | Sets 404 (secure setting missing), 400 (Oracle alias not found) or 500 (all other failures); the exact written envelope is not visible in source** |
| Local bare `try`/`catch` in `AdminController.GetConnectionInfo` | The three `AdminController` endpoints | Swallows a credential-split failure and still returns `200 OK` with an `Error` entry ([BR-DBC-024](business-rules.md#br-dbc-024-admin-split-failure-reported-with-status-200)); any other exception flows to the opaque middleware** |

## Request flow diagram

```mermaid
flowchart TD
    REQ["Client request"] --> PIPE["Middleware pipeline<br/>see hosting-pipeline.md"]
    PIPE --> ROUTE{"Route match"}
    ROUTE -->|"GET /v1/Connections/..."| C["ConnectionsController action"]
    ROUTE -->|"POST /v1/Admin/..."| A["AdminController action"]
    ROUTE -->|"No match"| NF["404 Not Found *"]
    C --> CAUTH{"Connections request authorized for<br>DBConnAPIRetrieveResource?"}
    A --> AAUTH{"Admin request authorized for<br>DBConnAPIRetrieveResource?"}
    CAUTH -->|"No"| DENY["401 / 403 ** (status not visible in source)"]
    AAUTH -->|"No"| DENY
    CAUTH -->|"Yes"| TPL["Read and format Environment API template"]
    AAUTH -->|"Yes"| ATPL["Read template and secure setting"]
    TPL -->|"Template missing or read fails"| ERRU["Unhandled/package error, status not visible"]
    TPL --> CACHE{"Cache hit?"}
    CACHE -->|"Yes"| OK["200 connection string"]
    CACHE -->|"No"| PROBE["Retrieve credential, compose string,<br>probe Oracle / SQL Server"]
    PROBE -->|"Success, cached"| OK
    PROBE -->|"Failure"| ERR["400 (Oracle) / 400* (SQL Server) /<br>404 / 500 via DynamicErrorHandler"]
    ATPL -->|"Read fails"| ERRU
    ATPL --> SPLIT["Split credential at first pipe, compose string;<br>no cache, no probe"]
    SPLIT --> OKA["200 JSON object (credentials, user, pw, connectionString)"]
    SPLIT -->|"Split fails"| OKE["200 with Error entry"]
```

## Endpoints by operation

| Endpoint | Operation |
| --- | --- |
| [`GET /v1/Connections/SQL/{server}/{instance}/{username}`](endpoints/connections.md#get-v1-connections-sql-server-instance-username) | OP-01 — see [Operations and processes](operations-processes.md) |
| [`GET /v1/Connections/PostgreSQL/{instance}/{username}`](endpoints/connections.md#get-v1-connections-postgresql-instance-username) | OP-02 — see [Operations and processes](operations-processes.md) |
| [`GET /v1/Connections/ORA/{instance}/{username}`](endpoints/connections.md#get-v1-connections-ora-instance-username) | OP-03 — see [Operations and processes](operations-processes.md) |
| [`POST /v1/Admin/GetOracleConnectionInfo`](endpoints/admin.md#post-v1-admin-getoracleconnectioninfo) | OP-04 — see [Operations and processes](operations-processes.md) |
| [`POST /v1/Admin/GetPostgresConnectionInfo`](endpoints/admin.md#post-v1-admin-getpostgresconnectioninfo) | OP-05 — see [Operations and processes](operations-processes.md) |
| [`POST /v1/Admin/GetSqlConnectionInfo`](endpoints/admin.md#post-v1-admin-getsqlconnectioninfo) | OP-06 — see [Operations and processes](operations-processes.md) |

## Related documentation
- [API index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Hosting pipeline](hosting-pipeline.md)
- [Authentication and authorization](authentication-authorization.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Data model](data-model.md)
- [Operational runbook](operational-runbook.md)
- [Tech debt](tech-debt.md)

> **Note:** Statements marked with `†` are derived from dependency library
> documentation via the Legends CLI. Statements marked with `*` were inferred
> from code structure or contextual evidence. Statements marked with `**` could
> not be confirmed; treat as unknown until verified.

## Sources
- DBConnectionAPI/DBConnectionAPI/Controllers/ConnectionsController.cs
- DBConnectionAPI/DBConnectionAPI/Controllers/AdminController.cs
- DBConnectionAPI/DBConnectionAPI/Services/ConnectionManager.cs
- DBConnectionAPI/DBConnectionAPI/Exceptions/ConnectionManagerException.cs
- DBConnectionAPI/DBConnectionAPI/Startup.cs